Skip to content

feat: Wire FDv2 connection-mode resolution in common_client#279

Merged
tanderson-ld merged 4 commits into
mainfrom
ta/SDK-2187/connection-mode-and-resolution-common
Jun 3, 2026
Merged

feat: Wire FDv2 connection-mode resolution in common_client#279
tanderson-ld merged 4 commits into
mainfrom
ta/SDK-2187/connection-mode-and-resolution-common

Conversation

@tanderson-ld
Copy link
Copy Markdown
Contributor

@tanderson-ld tanderson-ld commented May 29, 2026

Summary

Wires the FDv2 mode-resolution scaffolding (merged via #274) into the common_client runtime path. Keeps the FDv1 ConnectionMode enum and all existing public API signatures unchanged.

This is the first half of the further split of the original behavior PR (#275, now closed). The follow-up flutter-only PR wires this into the Flutter SDK.

LDCommonClient

  • setMode(ConnectionMode) keeps its FDv1 signature; internally maps the 3 legacy modes to ResolvedConnectionMode before forwarding to DataSourceManager.
  • New setResolvedMode(ResolvedConnectionMode) is the advanced FDv2 entry point. Documented as EAP / not-stable. No internal caller in this PR -- the Flutter SDK's ConnectionManager invokes it in the follow-up flutter PR.
  • DataSourceFactoriesFn (the public, optional constructor seam) stays typed Map<ConnectionMode, DataSourceFactory> so external callers can still customize streaming + polling. _backgroundFactory is SDK-managed (background is FDv2-only), and _composeFactoriesForManager translates the FDv1 map into the FDv2-keyed Map<FDv2ConnectionMode, DataSourceFactory> consumed by DataSourceManager.

DataSourceManager (internal, not publicly exported)

  • Active mode held as ResolvedConnectionMode.
  • Factory map keyed by FDv2ConnectionMode.
  • ResolvedOffline branches dispatch status as setOffline / networkUnavailable / backgroundDisabled depending on OfflineDetail.

Tests updated to match.


Note

Medium Risk
Changes core data-source connection and status behavior (including removal of manager-level network toggling); public API is preserved but internal mode transitions and offline semantics are more complex until the Flutter layer adopts setResolvedMode.

Overview
Wires FDv2 connection-mode resolution into the common_client runtime while keeping the public ConnectionMode API unchanged.

DataSourceManager now tracks FDv2ConnectionMode plus OfflineDetail, accepts ResolvedConnectionMode via setMode, and keys factories by FDv2 modes (including background). Offline no longer always means “set offline”: ResolvedOffline maps OfflineSetOffline, OfflineNetworkUnavailable, and OfflineBackgroundDisabled to the matching data-source status without starting a connection. Internal setNetworkAvailable on the manager is removed—network-unavailable behavior is expected to come through resolved offline modes instead.

LDCommonClient maps legacy setMode(ConnectionMode) to resolved modes, adds EAP setResolvedMode, composes FDv1 custom factories into an FDv2 factory map via _composeFactoriesForManager, and registers an SDK-managed background polling factory. setNetworkAvailability no longer touches the data source manager (events only).

Tests are updated for FDv2 modes and the new offline status branches.

Reviewed by Cursor Bugbot for commit 0921328. Bugbot is set up for automated code reviews on this repo. Configure here.

Wires the FDv2 mode-resolution scaffolding (merged via #274) into the
common_client runtime path while keeping the FDv1 ConnectionMode enum
and all existing public API signatures unchanged.

LDCommonClient:
- setMode(ConnectionMode) keeps its FDv1 signature and now maps the 3
  legacy modes to ResolvedConnectionMode internally before forwarding
  to DataSourceManager.
- New setResolvedMode(ResolvedConnectionMode) is the advanced FDv2
  entry point. Documented as EAP / not-stable. No internal caller in
  this PR; the Flutter SDK's ConnectionManager invokes it in the
  follow-up flutter PR.
- DataSourceFactoriesFn (the public, optional constructor seam)
  remains typed Map<ConnectionMode, DataSourceFactory> so external
  callers can still customize streaming + polling. _backgroundFactory
  is SDK-managed (background is FDv2-only), and
  _composeFactoriesForManager translates the FDv1 map into the
  FDv2-keyed Map<FDv2ConnectionMode, DataSourceFactory> consumed by
  DataSourceManager.

DataSourceManager (internal, not publicly exported):
- Active mode held as ResolvedConnectionMode.
- Factory map is keyed by FDv2ConnectionMode.
- ResolvedOffline branches dispatch status as setOffline /
  networkUnavailable / backgroundDisabled depending on OfflineDetail.

Tests updated to match.
@tanderson-ld tanderson-ld marked this pull request as ready for review May 29, 2026 14:36
@tanderson-ld tanderson-ld requested a review from a team as a code owner May 29, 2026 14:36
Copy link
Copy Markdown

@cursor cursor Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 2d2ff51. Configure here.

Comment thread packages/common_client/lib/src/ld_common_client.dart
tanderson-ld and others added 3 commits May 29, 2026 11:12
Splits the active mode and offline detail into two fields:

- _activeConnectionMode: FDv2ConnectionMode -- drives factory lookup
  (matches the factory map's key type directly).
- _offlineDetail: OfflineDetail -- semantically meaningful only when
  _activeConnectionMode is FDv2Offline; carries a stale value in
  other modes and is intentionally only read inside the FDv2Offline
  arm of _setupConnection.

ResolvedConnectionMode is now a true boundary type: consumed by
setMode, decomposed into the two fields, then discarded. This
removes the .connectionMode getter call previously needed for
factory lookup.

setMode dedup is rewritten to compare the FDv2 mode and (when
offline) the offline detail explicitly, so a redundant call with
the same effective state still short-circuits.

Constructor initializes _offlineDetail to OfflineSetOffline() as a
placeholder; it is overwritten the next time setMode receives a
ResolvedOffline value.
@tanderson-ld
Copy link
Copy Markdown
Contributor Author

This should be merged with #280 before any releases are cut.

@tanderson-ld tanderson-ld merged commit ceb931f into main Jun 3, 2026
8 of 9 checks passed
@tanderson-ld tanderson-ld deleted the ta/SDK-2187/connection-mode-and-resolution-common branch June 3, 2026 19:30
tanderson-ld pushed a commit that referenced this pull request Jun 3, 2026
🤖 I have created a release *beep* *boop*
---


##
[1.11.0](launchdarkly_common_client-v1.10.0...launchdarkly_common_client-v1.11.0)
(2026-06-03)


### Features

* Wire FDv2 connection-mode resolution in common_client
([#279](#279))
([ceb931f](ceb931f))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Version and changelog/manifest updates only; no runtime code changes
in this PR.
> 
> **Overview**
> Release Please PR that **bumps** `launchdarkly_common_client` from
**1.10.0** to **1.11.0** and syncs the release manifest
(`.release-please-manifest.json`).
> 
> The **CHANGELOG** entry for 1.11.0 documents the shipped feature from
[#279](#279):
wiring **FDv2 connection-mode resolution** in common_client (building on
the FDv2 connection/resolved-mode types added in 1.10.0). **No
application or library source changes** appear in this diff—only version
and release notes.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
2c1d100. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
tanderson-ld added a commit that referenced this pull request Jun 4, 2026
## Summary

Wires the FDv2 mode-resolution machinery into the Flutter SDK's
`ConnectionManager`. Stacked on the common_client PR (#279); rebase onto
`main` once that merges.

This is the second half of the further split of the original behavior PR
(#275, now closed).

**ConnectionManager**
- `DartClientAdapter` forwards `ResolvedConnectionMode` to
`LDCommonClient.setResolvedMode` (the new advanced FDv2 entry point from
#279).
- `ConnectionManagerConfig.backgroundConnectionMode` (new) is typed
`FDv2ConnectionMode`. `initialConnectionMode` stays `ConnectionMode`
(legacy).
- `disableAutomaticBackgroundHandling` keeps its original name.
- Automatic mode resolution uses `resolveMode` +
`flutterDefaultResolutionTable`; `setMode` override path supports the 3
FDv1 modes only (background is auto-resolved, not user-selectable).

**Flutter umbrella re-exports** cover the FDv2 types consumed by this PR
(`FDv2ConnectionMode` + four subtypes, `ResolvedConnectionMode` family,
`OfflineDetail` family,
`ModeState`/`ModeResolutionEntry`/`resolveMode`/`flutterDefaultResolutionTable`).

**Platform defaults** (`io_config` / `js_config` / `stub_config` /
`flutter_default_config`) return `FDv2ConnectionMode` for the background
slot.

**LDClient** passes `backgroundConnectionMode` to the
`ConnectionManager` and sets `offline=true` post-construction (no longer
forces initial mode to offline in config).

Tests updated to match.

**Depends on** #279 -- the `LDCommonClient.setResolvedMode` method this
PR consumes lives there.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Connection and data-source behavior changes across
foreground/background and network transitions (including new status
reasons and mobile background polling), which can affect flag freshness
and event delivery even though public FDv1 `setMode` remains.
> 
> **Overview**
> **Flutter `ConnectionManager`** now picks a
**`ResolvedConnectionMode`** from app foreground/background, network,
config, and optional overrides using **`resolveMode`** and
**`flutterDefaultResolutionTable`** (custom tables supported). It
forwards modes through **`DartClientAdapter.setResolvedMode`**, adds
**`backgroundConnectionMode`**, and **`setMode(FDv2ConnectionMode?)`**
for manual override. Background transitions still **flush** events;
event sending rules are tied to offline / background +
**`runInBackground`**.
> 
> **`common_client`** **`DataSourceManager`** is keyed on
**`FDv2ConnectionMode`** factories and
**`setMode(ResolvedConnectionMode)`**, mapping offline
**`OfflineDetail`** to **`setOffline` / `setNetworkUnavailable` /
`setBackgroundDisabled`**. **`LDCommonClient`** composes FDv1 factories
into FDv2 (including an SDK-managed **background polling** factory),
exposes **`setResolvedMode`**, and stops pushing network availability
into the data source manager (Flutter resolves network loss to
**`ResolvedOffline(OfflineNetworkUnavailable)`** instead).
> 
> **Platform defaults**: mobile uses **`FDv2Background`** and enables
automatic background/network handling by default; desktop and web
default the background slot to offline and disable those detectors
unless configured. **`LDClient`** passes the platform background slot
and sets **`ConnectionManager.offline`** after build when
**`config.offline`**. FDv2 types are re-exported from the Flutter
package; **`launchdarkly_common_client`** is bumped to **1.11.0**.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
bc0a1ac. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants